Summary

When a hook callback returns None or a non-dict value, the SDK currently crashes with a confusing AttributeError when trying to call .items() on the return value in _convert_hook_output_for_cli(). This PR adds explicit validation with clear error messages to help users debug their hook callbacks.

Changes

• Add HookCallbackError exception class for hook-related errors
• Validate hook callback return type immediately after calling the callback
• Provide helpful error messages including the callback ID and expected type
• Export the new error class from the package

Example

Before this change, a hook returning None would cause:

AttributeError: 'NoneType' object has no attribute 'items'

After this change:

HookCallbackError: Hook callback returned None. Expected a dict (HookJSONOutput). Did you forget to return a value? (callback_id: my_hook)

Test plan

• Add tests for hook callbacks returning None
• Add tests for hook callbacks returning strings
• Add tests for hook callbacks returning lists
• Add tests for valid dict returns (success cases)
• Verify existing tests pass